feat(cli)!: make init the single entry point, fold in and remove create - #4883
Merged
Conversation
- `cli/__init__.py`: list the actual command surface — `init` (entry
point), `create`, and `eval`
- Replace the "agent-ready" terminology across the CLI with plain language
("initialize a project" / "set up for coding agents"), matching the docs.
Rename the internal `_print_agent_ready` helper to `_print_ready` and
change its message to "Your project is ready."
Trim the orientation paragraph to what the human reader needs — this file is yours; AGENTS.md/CLAUDE.md are the agent's guide, picked up automatically. Drop the breakdown of what AGENTS.md teaches the agent.
`pipecat init` is now the single entry point for building a Pipecat app.
It still writes the coding-agent guide (AGENTS.md + CLAUDE.md) and now
also scaffolds a runnable bot — interactively, or non-interactively from
flags or a config file:
pipecat init . --bot-type web -t daily --mode cascade \
--stt deepgram_stt --llm openai_llm --tts cartesia_tts
Scaffolding is directory-first and in-place (project name derived from the
target dir); create's --output/-o and --name-subfolder layout are gone. A
missing target with scaffold flags defaults to the current directory so an
automated run never hangs on a prompt.
The scaffolder internals move to pipecat/cli/scaffold.py. `pipecat create`
is removed; a hidden stub points users to `pipecat init`.
Codecov Report❌ Patch coverage is
... and 6 files with indirect coverage changes 🚀 New features to boost your workflow:
|
Group the scaffold flags into "Scaffold options" (the structural, value-taking choices) and "Scaffold features" (the optional boolean toggles) instead of one flat wall of ~24 options. Drop the help= override on the init command so its docstring (summary + examples) drives `pipecat init --help`; tighten that description and flatten the examples to single lines so they render cleanly. Sharpen the TARGET argument help to cover in-place scaffolding, `.`, and quickstart.
… flags Split run_non_interactive_scaffold into resolve_scaffold_config (merge + validate + --dry-run) and generate_scaffold (write), so `pipecat init` validates before writing the agent guide. An incomplete invocation like `pipecat init . --bot-type web` now fails atomically instead of dropping AGENTS.md/CLAUDE.md and then erroring. Also warn when scaffold flags are passed to `pipecat init quickstart` (a fixed preset) instead of silently ignoring them.
AGENTS.md is the coding-agent guide; the bare/quickstart interactive forms are for humans (covered in GETTING_STARTED.md) and the scaffold section's warning already tells the agent to avoid the interactive form.
Make the three guide files `pipecat init` writes (AGENTS.md, CLAUDE.md, GETTING_STARTED.md) follow one uniform rule instead of asymmetric ones. Previously AGENTS.md and GETTING_STARTED.md were always overwritten while CLAUDE.md was preserved — which silently destroyed a non-Claude user's hand-edited AGENTS.md on every re-run. Now: absent -> write; present -> keep it (never clobber silently); `--overwrite-guide` (renamed from `--force`, now covering all three files) to overwrite. A re-run reports what it did per file, and if a kept guide carries an older Pipecat's version stamp it prints a heads-up pointing at `--overwrite-guide` — so staleness is surfaced, not silent. - init.py: `_write_guide_file` helper (absent/keep/overwrite) + `_stamped_version` + `_print_refresh_summary`; footer text and flag/param renamed - tests: re-run now preserves; add stale-nudge and summary coverage
Contributor
👍 |
kompfner
reviewed
Jun 25, 2026
| # the command's docstring (summary + examples) drives `pipecat init --help`. | ||
| app.command("init")(init_command) | ||
|
|
||
| # `pipecat create` was removed (folded into `init`). Keep a hidden stub so an old |
kompfner
reviewed
Jun 25, 2026
Contributor
There was a problem hiding this comment.
If this PR lands before mine, I'll rebase and fix my README.md updates to properly reference the new single-entry-point version of init.
Contributor
Author
There was a problem hiding this comment.
FYI: I'll merge later this afternoon.
When `pipecat init` is re-run in a terminal and finds a guide written by
an older Pipecat, it now offers to refresh it ("Refresh the guide files
now? [Y/n]") rather than only printing a nudge that's easy to miss before
the build-method prompt. Re-running signals intent, so a one-keystroke
refresh is the expected payoff. Non-interactive runs keep the printed
`--overwrite-guide` nudge.
Integrating preserve-by-default (this branch) with init's scaffold path (base): scaffolding over an existing guide now keeps it instead of refreshing it, so update the in-place test to assert preservation.
feat(cli): preserve existing guide files on `pipecat init` re-run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
pipecat initthe single entry point for building a Pipecat app and removespipecat create, folding its scaffolding intoinit.createshipped only in the last release, so we're opting for a clean break now rather than carrying two commands (and two location models).pipecat initstill writes the coding-agent guide (AGENTS.md+CLAUDE.md) and now also scaffolds a runnable bot — interactively, or non-interactively from flags or a config file:pipecat init . --bot-type web -t daily --mode cascade \ --stt deepgram_stt --llm openai_llm --tts cartesia_ttsThis shape fits the real agent workflow: a developer runs
pipecat init my-botto lay down the guide, opens a coding session in that directory, and the agent scaffolds in place withpipecat init . ….What changed
init. A newpipecat/cli/scaffold.pyholds the scaffolder — the interactive wizard, the quickstart preset, and the non-interactive flag/config-file build — reusing the existing config validator and project generator.pipecat initgained the full scaffold flag surface (minus--output/-o). Scaffolding is directory-first and in-place: the project name is derived from the target directory, and./ no target means the current directory, so an automated run never hangs on a prompt.pipecat createremoved. A hidden stub points users topipecat initinstead of Click's bare "No such command".AGENTS.mdtemplate updated so coding agents scaffold withpipecat init . ….pipecat init --helpreorganized into grouped panels ("Scaffold options" / "Scaffold features") with usage examples.This PR also absorbs the earlier CLI-cleanup commits (docstring tidy, drop "agent-ready" jargon, streamline
GETTING_STARTED.md) that lived in #4868 — that PR is superseded by this one.Breaking change
pipecat createis removed. Usepipecat init(pipecat init --help,pipecat init --list-options).pipecat create quickstart→pipecat init quickstart. The--output/-oflag and the--name→./<name>-subfolder layout are gone — scaffolding is always in-place in the target directory.Test plan
uv run pytest tests/cli/— full CLI suite passesuv run ruff check/ruff format --check— clean--dry-run, quickstart) and the removed-createstub🤖 Generated with Claude Code